Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d21 / apicsamp.arc / README.DOC < prev next >

Wrap

Text File | 1989-02-24 | 21KB | 521 lines

DESQview API C Sampler, Copyright (c) 1989 Quarterdeck Office Systems. Quarterdeck Office Systems 150 Pico Boulevard Santa Monica, CA 90405 (213) 392-9851 Fax (213) 399-3802 DESQview API C Library ---------------------- The DESQview API (Application Program Interface) C Library is a set of over 200 functions that gives your C program full access to the DESQview API. Using the C Library a program can ask the DESQview API to: o display information in windows and change the color, dimensions, position, and ordering of windows on the screen, o handle all keyboard and mouse input to menus and forms, o schedule processing after a certain time interval or at a certain time of day, o spawn subtasks for performing background operations such as printing, recalculating, and communicating, o communicate between the various tasks in the system, o disable, limit, or enhance the standard DESQview user interface. The DESQview API C Library consists of over 200 functions divided into groups according to the type of object they manipulate. These objects include: applications, fields, keyboards, mailboxes, objectqs, panels, pointers, timers, tasks, and windows. The groupings correspond closely to the organization of the DESQview API Reference Manual, a copy of which is included with the C Library. DESQview API C Library functions are divided into 12 logical groups. Every function in a group has the same 4 character prefix, usually indicating the type of object the function operates on. The groups are: Prefix Group ------ ----- api_ General Functions app_ Application (parent task) Management Functions fld_ Field Management Functions key_ Keyboard Management Functions mal_ Mailbox Management Functions obq_ Objectq Management Functions pan_ Panel Management Functions ptr_ Pointer Management Functions qry_ Query Functions tim_ Timer Management Functions tsk_ Task Management Functions win_ Window Management Functions The DESQview API C Library supports the Microsoft C, Lattice C, Borland Turbo C and Metaware High C compilers for all memory models. Source code for the C Library is included so that the library can be converted for use with other compilers if needed. DESQview API C Interfaces ------------------------- Listed below are the DESQview API C interfaces available with the DESQview API C Library. General Functions api_beginc begin critical region api_cancel cancel current Window Mgr operation api_endc end critical region api_exit exit API interface api_freebit disconnect 2nd level interrupt handler api_getbit define 2nd level interrupt handler api_getcrit get critical region nesting level api_getmem get system memory buffer api_init initialize API interface api_isobj determine if a given handle is valid api_justify enable/disable automatic justification of window api_kmouse turn keyboard mouse on and off api_level define API revision level required by application api_objtype determine the object type of a given handle api_pause give other tasks a chance to run api_poke display debug information/bottomline of screen api_putmem return system memory buffer api_pushkey push key into input stream api_setbit schedule 2nd level interrupt handler api_shadow get task's logical window buffer& start shadowing api_sound make a sound api_update redraw portion of logical window and stop shadowing Application Management Functions app_foreonly indicate whether a task can run in background app_free free an application and its window app_goback force an application into background app_gofore force an application into foreground app_hide hide all windows of an application app_new create a new application in the current process app_number get current applications SWITCH number app_show display all windows of an application app_start start a new application in a new process app_suspend suspend & hide all application's tasks Field Management Functions fld_altmode set Alternate field processing mode fld_attr fill a field with a given attribute fld_char fill a field with a given character fld_clear clear a field fld_cursor move cursor to a field fld_entry change field table entry fld_header change field table header fld_marker define selected field marker character fld_point move pointer to given position in field fld_protattr set Protected Attributes field processing mode fld_reset reset selected and modified bits fld_scroll scroll a field fld_swrite write a string into a field fld_type change the type of a field fld_write write characters into a field Keyboard Management Functions key_addto set keyboard behavior flags key_close disconnect keyboard from its window key_erase discard pending keyboard input key_free free a keyboard object key_getc wait for next key (keystroke mode) key_getflags get keyboard control flags key_getpri get objectq priority level of keyboard key_me get current tasks keyboard handle key_new create a new keyboard object key_of get handle of a given task's keyboard key_open attach keyboard to a given window key_read read input from keyboard key_setesc define function to filter keys in field mode key_setflags replace keyboard control flags key_setpri set objectq priority level of keyboard key_sizeof get # keyboard messages pending key_status get status of last keyboard message key_subfrom clear keyboard behavior flags key_write write data to keyboard Mailbox Management Functions mal_addr return sender of last message mal_addto send message by value with given status mal_close close a mailbox mal_erase erase all pending messages mal_find find a mailbox by name mal_free free a mailbox object mal_getflags get mailbox control flags mal_getpri get objectq priority level of mailbox mal_lock lock access to a resource mal_me get handle of MAILME mailbox mal_name assign a global name to a mailbox mal_new create a new mailbox mal_of get handle of a given task's mailbox mal_open open a mailbox mal_read wait for next message mal_setflags replace mailbox control flags mal_setpri set objectq priority level of mailbox mal_sizeof get # messages pending mal_status get status of last message received mal_subfrom send message by reference with given status mal_unlock unlock access to a resource mal_write send a message by value with status zero Objectq Management Functions obq_close close the task's objectq obq_erase erase contents of the task's objectq obq_open open the task's objectq obj_read wait for any object to have input obq_sizeof get # of objectq entries pending obq_status determine if the task's objectq is open obq_subfrom remove an object from the task's obectq Panel Management Functions pan_apply display a named panel & prepare for input pan_close close a panel file pan_dir get list of panels in the panel file pan_free free a panel object pan_new create a panel object pan_open open a panel file pan_sizeof get # panels in the panel file pan_status get status of last pan_open or pan_apply Pointer Management Functions ptr_addto set pointer control flags ptr_close close a pointer object ptr_erase erase pending pointer messages ptr_free free a pointer object ptr_getflags get pointer control flags ptr_getpri get objectq priority level of pointer ptr_getscale get current scaling factors ptr_new create a new pointer object ptr_open open pointer and assign to a window ptr_read wait for next pointer message ptr_setflags replace pointer control flags ptr_setpri set objectq priority level of pointer ptr_setscale set current scaling factors ptr_sizeof get # messages pending ptr_status get button state from last message received ptr_subfrom clear pointer control flags ptr_write move the pointer to a given position Query Functions qry_atread TRUE if win_read and win_readn reads attributes qry_attr get current output attribute qry_color get physical attribute for given logical attribute qry_ctrl TRUE if processing control codes qry_cursor get current cursor position qry_entry get field table entry qry_field get contents of a field qry_frame TRUE if the window has a frame qry_frattr get current frame attribute qry_header get field table header qry_hidden TRUE if the window is hidden qry_kmouse TRUE if using a keyboard mouse qry_leave TRUE if leaving attribute untouched when writing qry_lsize get size of logical window buffer qry_logattr TRUE if using logical attributes qry_origin get origin of physical window relative to logical qry_position get position of physical window qry_size get size of physical window qry_title get window's title qry_type get type of field Timer Management Functions tim_addto start a timer for a given interval tim_close close a timer object tim_erase stop a running timer tim_free free a timer object tim_getpri get objectq priority level of timer tim_len get time remaining until timer expires tim_new create a new timer object tim_open open a timer object tim_read wait for timer to expire tim_setpri set objectq priority level of timer tim_sizeof get time since a timer started running tim_status determine if a timer is running tim_write start a timer for a given time of day Task Management Functions tsk_free free a task and its window tsk_geterror get error handling level of current task tsk_me get handle of current task tsk_new create a new task tsk_pgmint software interrupt another task tsk_post restart a task and post its Objectq tsk_seterror set error handling level of current task tsk_start restart a stopped task tsk_stop temporarily stop a task Window Management Functions win_addto write characters and attributes to a window win_adopt adopt a window win_allow specify which DESQview commands are allowed for a window win_async define asynchronous notify function win_atread sets read mode to read either charaters or attributes win_attach attach window to its parent task window win_attr set current output attribute win_blanks write blanks to a window win_bottom make window bottommost in its application win_buffer get pointer to window's logical window buffer win_cancel cancel notification on a given event win_color change logical attribute mapping win_ctrl enable/disable interpretation of control characters win_cursor move window's logical cursor win_dflt change default notify window win_disallow specify which DESQview commands are not allowed for a window win_disperor display an error message window win_eof TRUE if logical cursor is beyond end of window win_erase clear window win_frame enable/disable display of a window's frame win_frattr define window frame attribute win_free remove a window from the screen and free its handle win_hcur display hardware cursor at logical cursor position win_hide marks a window as hidden win_leave leave existing attribute when writing to a window win_len return width of logical window win_locate return which window is visible at the given screen row/col win_logattr use logical/physical attributes win_lsize set windows logical dimensions win_maxsize set windows maximum physical dimensions win_me get current task's window handle win_minsize set windows minimum physical dimensions win_move move physical window win_new create a new window win_notify enable notification on a given event win_nread read n characters from a window win_open fill a window with a given character win_origin define portion of logical window viewed in the physical window win_orphan orphan a window win_paste define window as current clipboard window win_point jump mouse to logical cursor position win_poswin position window relative to another window win_printf write formatted data to a window win_putc write a character/attribute pair to a window win_read read rest of current line from window win_redraw redraw a window win_reorder reorder an applications windows win_repattr write an attribute to a window n times win_repchar write a character to a window n times win_resize set physical dimensions of window win_scroll scroll all or part of a window win_sizeof get total number of characters in logical window win_stream write a stream to a window win_subfrom write attributes to a window win_swrite write a zero terminated string to a window win_title change a windows title win_top make window topmost in application win_topsys make window topmost in system win_unhide marks a window as not hidden win_write write characters to a window DESQview API C Examples ----------------------- Also included in the C Library is a C Examples diskette, containing sample programs that show the basics of writing DESQview-specific programs. Examples cover the creation of a simple pop-up menu, creation of a complex menu (using timers and waiting on multiple events), tracking of a mouse, subtask creation and termination, intertask communications and named mailboxes, asynchronous notifies, and process creation. The examples are presented roughly in order of increasing complexity. The primary purpose of each is to show: Example Shows ------- ----- hello a minimal DESQview-specific program fruit a simple pop-up menu point how to track the mouse washer a complex menu, timers, and waiting on multiple events snakes subtask creation and termination server intertask communication and named mailboxes request intertask communication and asynchronous notifies examples process creation The following are the opening comments for each example program: /**************************************************************** * * Name: HELLO * * Function: display 'hello world' in the task window * * Shows how to: 1. write a 'minimal' DESQview-specific program. * 2. initialize and disable the C interfaces. * 3. detect DESQview's presence. * 4. enable DESQview extensions. * 5. write to the default task window. * ****************************************************************/ /**************************************************************** * * Name: FRUIT * * Function: display a pop-up menu and report selections * * Shows how to: 1. create a new window and associated keyboard. * 2. define the contents and fields for a menu. * 3. move and display a window. * 4. take input from a menu. * ****************************************************************/ /**************************************************************** * * Name: POINT * * Function: track the pointer as it passes through the window. * * Shows how to: 1. create and read a pointer object. * 2. force the keyboard mouse ON, if applicable. * 3. display single characters in a window. * 4. jump the pointer. * 5. change cursor position for a window. * ****************************************************************/ /**************************************************************** * * Name: WASHER * * Function: Emulate a washing machine control panel. * * Shows how to: 1. construct complex menus (dialogues) including * select, input, output, and inactive fields. * 2. change field types dynamically. * 3. implement "radio button" select fields. * 4. use a timer object to measure time intervals. * 5. use an objectq to wait for multiple events. * ****************************************************************/ /**************************************************************** * * Name: SNAKES * * Function: display multiple "snakes" each controlled by a * separate task. * * Shows how to: 1. create and terminate subtasks. * 2. use mail to send initial data to a new task. * 3. use a semaphore to control access to a * resource, in this case the window. * 4. read and write the window contents. * ****************************************************************/ /**************************************************************** * * Name: SERVER * * Function: This program provides a very simple file * management service. It maintains a database * consisting of arbitrary length text strings and * allows the database to be queried for all * records containing a specified substring. * Queries are sent by mail from REQUEST windows. * The results are returned to the REQUESTers * mailbox. * * Shows how to: 1. use named mailboxes to detect multiple * instances of the same program. * 2. use named mailboxes to control access to * public utilities. * 3. send and receive mail. * 4. use a timer object to display a running clock. * 5. optimize a program by performing the equivalent of * multiple C Library calls in one encoded stream. * ****************************************************************/ /**************************************************************** * * Name: REQUEST * * Function: Provides a front-end for the SERVER program. * Takes a string entered by the user and sends * requests to the SERVER to either add the string * to the database or find all records that contain * the string. * * Shows how to: 1. find a named mailbox. * 2. read a key-at-a-time from the keyboard. * 3. use an asynchronous notify function to * detect attempts to close the window. * ****************************************************************/ /**************************************************************** * * Name: EXAMPLES * * Function: Display a menu listing the example programs and * start an example as a new process when so requested. * * Shows how to: 1. read a DESQview Program Information File (DVP) * from disk. * 2. adjust the DVP to reflect the current drive and * directory. * 3. start a new process using the DVP. * ****************************************************************/ Installing the C Examples ------------------------- To install the example programs, copy all files from the diskette into any directory of your choice and use the DESQview "Add a Program" feature to add programs from that directory. Select the only option that you are presented, the "C Examples" program. When you then open a "C Examples" window, a menu will be presented that lets you run the other example programs.